package jndi.ldap.biz;

import jndi.ldap.LdapConnection;
import jndi.ldap.domains.LdapUser;

import javax.naming.directory.SearchControls;
import javax.naming.directory.SearchResult;
import java.util.List;


/**
 * This is an interface for LDAP operations.
 * <p>
 * All of operations at here are based on a LDAP context (here named connection)
 * </p>
 *
 * @author Roy.Yang
 */
public interface LdapOperator {

    /**
     * Perform a Search operation with specific filter and SearchControls.
     * It will visit each of the default configured baseObjects.
     *
     * @param searchFilter the search filter
     * @param cons         the search controls, refer to {@link javax.naming.directory.SearchControls}
     * @return the result
     */
    public List<SearchResult> search(String searchFilter, SearchControls cons);

    /**
     * Search sth form LDAP server by given searchBase, searchFilter and
     * SearchControls. This API is similar with
     * {@link javax.naming.directory.DirContext#search(String, String, javax.naming.directory.SearchControls)}
     *
     * @param searchBase   the base DN on which this search operation affects.
     * @param searchFilter the search filter.
     * @param cons         the search controls
     *                     {@link javax.naming.directory.SearchControls}.
     * @return the result
     */
    public List<SearchResult> search(String searchBase, String searchFilter, SearchControls cons);

    /**
     * Find user from default baseOjbects.
     *
     * @param username the unique user name
     * @return ldap user
     */
    public LdapUser findUser(String username);

    /**
     * Find users from default baseOjbects.
     *
     * @param usernameFilter the user name filter
     * @return the ldap user list
     */
    public List<? extends LdapUser> findUsers(String usernameFilter);

    /**
     * Get the RootDSE.
     * <p>
     * The RootDSE is a standard attribute defined in the LDAP version 3.0
     * specification. The RootDSE contains information about the directory
     * server, including its capabilities and configuration.
     * </p>
     *
     * @return the RootDSE
     */
    public SearchResult getRootDSE();

    /**
     * Get the connection which used by this Operations object.
     *
     * @return the connection
     */
    public LdapConnection getConnection();

    /**
     * Set the LDAP connection (context) so that we can user these operations.
     *
     * @param connection the LDAP connection.
     */
    public void setConnection(LdapConnection connection);

}